Class

ListBox (SUI)

Displays a list of choices, represented by ListItem objects.

When you create the object, you specify whether it allows the user to select only one or multiple items. If a list contains more items than can be displayed in the available area, a scrollbar may appear that allows the user to scroll through all the list items.
You can specify the items on creation of the list object, or afterward using the list object's add() method. You can remove items programmatically with the list object's remove() and removeAll() methods. You can create a list box with multiple columns; in this case, each row is a selectable choice, and each ListItem represents one row.

QuickLinks

add, addEventListener, dispatchEvent, find, hide, notify, onActivate, onChange, onDeactivate, onDoubleClick, onDraw, onShortcutKey, remove, removeAll, removeEventListener, show

Hierarchy

Object

ListBox (SUI)

Properties

Property	Type	Access	Description
active	Boolean	r/w	True if this element is active. An active control is the one with keyboard focus–that is, the one that accepts keystrokes, or in the case of a Button, is selected when the user types Return or Enter in Windows, or the space bar in Mac OS.
alignment	String	r/w	The alignment style for this element. If defined, this value overrides the alignChildren setting for the parent container. This can be a single string, which indicates the alignment for the orientation specified in the parent container, or an array of two strings, indicating both the horizontal and vertical alignment (in that order). Allowed values depend on the orientation value of the parent container. They are not case sensitive. • For orientation=row:top, bottom, fill • For orientation=column: left, right, fill • For orientation=stack:top, bottom, left, right, fill
bounds	Bounds	r/w	The boundaries of the element, in parent-relative coordinates. Setting an element's size or location changes its bounds property, and vice-versa.
children	Array of Object	readonly	An array of child ListItem elements.
columns	Object	readonly	For a multi-column list box, the column properties. A JavaScript object with two read-only properties whose values are set by the creation parameters: • titles: An array of column title strings, whose length matches the number of columns specified at creation. • preferredWidths: An array of column widths, whose length matches the number of columns specified at creation.
enabled	Boolean	r/w	True if this element is enabled. An enabled element can accept input, according to its type. When false, control elements do not accept input, and all types of elements have a dimmed appearance.
graphics	ScriptUIGraphics	readonly	The graphics object that can be used to customize the element's appearance, in response to the onDraw() event.
helpTip	String	r/w	The help text that is displayed when the mouse hovers over the element.
indent	Number (min: 0)	r/w	The number of pixels to indent the element during automatic layout. Applies for column orientation and left alignment, or row orientation and top alignment.
itemSize	Dimension	r/w	The width and height in pixels of each item in the list. Used by auto-layout to determine the preferredSize of the list, if not otherwise specified. If not set explicitly, the size of each item is set to match the largest height and width among all items in the list
items	Array of ListItem	readonly	The array of choice items displayed in the list. Access this array with a 0-based index. To obtain the number of items in the list, use items.length.The objects are created when items are specified on creation of the parent list object, or afterward using the list control's add() method. Each item has a selected property that is true when it is in the selected state.
location	Point	r/w	The upper left corner of this element relative to its parent. The location is defined as [bounds.x, bounds.y]. Setting an element's location changes its bounds property, and vice-versa.
maximumSize	Dimension	r/w	The maximum height and width to which the element can be resized.
minimumSize	Dimension	r/w	The minimum height and width to which the element can be resized.
parent	Object	readonly	The parent element.
preferredSize	Dimension	r/w	The preferred size, used by layout managers to determine the best size for each element. If not explicitly set by a script, value is established by the UI framework in which ScriptUI is employed, and is based on such attributes of the element as its text, font, font size, icon size, and other UI framework-specific attributes.A script can explicitly set this value before the layout manager is invoked in order to establish an element size other than the default.
properties	Object	r/w	An object that contains one or more creation properties of the control (properties used only when the element is created). Creation properties of a ListBox object can include: • multiselect: When false (the default), only one item can be selected. When true, multiple items can be selected. • items: An array of strings for the text of each list item. An item object is created for each item. An item with the text string "-" creates a separator item. Supply this property, or the items argument to the add() method, not both. This form is most useful for elements defined using Resource Specifications. • numberOfColumns: A number of columns in which to display the items; default is 1. When there are multiple columns, each ListItem object represents a selectable row. Its text and image values specify the label in the first column, and the subitems property specifies the labels in the additional columns. • showHeaders: True to display column titles. • columnWidths: An array of numbers for the preferred width in pixels of each column. • columnTitles: A corresponding array of strings for the title of each column, to be shown if showHeaders is true.
selection	ListItem	r/w	The currently selected item for a single-selection list, or an array of items for current selection in a multi-selection list. Setting this value causes the selected item to be highlighted and to be scrolled into view if necessary. If no items are selected, the value is null. Set to null to deselect all items. You can set the value using the index of an item or an array of indices, rather than object references. If set to an index value that is out of range, the operation is ignored. When set with index values, the property still returns object references. • If you set the value to an array for a single-selection list, only the first item in the array is selected. • If you set the value to a single item for a multi-selection list, that item is added to the current selection.
shortcutKey	String	r/w	The key sequence that invokes the onShortcutKey() callback for this element (in Windows only).
size	Dimension	r/w	The current dimensions of this element. Initially undefined, and unless explicitly set by a script, it is defined by a LayoutManager . A script can explicitly set size before the layout manager is invoked to establish an element size other than the preferredSize or the default size, but this is not recommended. Defined as [bounds.width, bounds.height]. Setting an element's size changes its bounds property, and vice-versa.
type	String	readonly	The element type; "listbox".
visible	Boolean	r/w	True if this element is shown, false if it is hidden. When a container is hidden, its children are also hidden, but they retain their own visibility values, and are shown or hidden accordingly when the parent is next shown.
window	Window (SUI)	readonly	The window that this element belongs to.
windowBounds	Bounds	readonly	The bounds of this element relative to the top-level parent window.

Methods

Events

void onActivate ()
An event-handler callback function, called when the element acquires the keyboard focus.
Called when the user gives the control the keyboard focus by clicking it or tabbing into it.

void onChange ()
An event-handler callback function, called when the content of the element has been changed

void onDeactivate ()
An event-handler callback function, called when the element loses the keyboard focus.
Called when the user moves the keyboard focus from the previously active control to another control.

void onDoubleClick ()
An event-handler callback function, called when an item in the listbox is double-clicked
Check the selection property to identify the item that was double-clicked.

void onDraw ()
An event-handler callback function, called when the window is about to be drawn.
Allows the script to modify or control the appearance, using the control's associated ScriptUIGraphics object. Handler takes one argument, a DrawState object.

void onShortcutKey ()
An event-handler callback function, called when the element's shortcutKey sequence is typed in the active window.
In Windows only.

Instances

ListItem add (type: String[, text: String])
Adds an item to the choices in this list.
Returns the item control object. If this is a multi-column list box, each added ListItem represents one selectable row. Its text and image values specify the label in the first column, and the subitems property specifies the labels in the additional columns.
Parameter Type Description

type String The type of the child element, the string "item".

text String The localizable text label for the item. (Optional)

Boolean addEventListener (eventName: String, handler: Function[, capturePhase: Boolean=false])
Registers an event handler for a particular type of event occuring in this element.
Parameter Type Description

eventName String The name of the event.
Event names are listed in the JavaScript Tools Guide.

handler Function The function that handles the event.
This can be the name of a function defined in the extension, or a locally defined handler function to be executed when the event occurs. A handler function takes one argument, the UIEvent object.

capturePhase Boolean When true, the handler is called only in the capturing phase of the event propagation. (default: false)
Default is false, meaning that the handler is called in the bubbling phase if this object is an ancestor of the target, or in the at-target phase if this object is itself the target.

Event dispatchEvent ()
Simulates the occurrence of an event in this target.
A script can create a UIEvent object for a specific event and pass it to this method to start the event propagation for the event.

ListItem find (text: String)
Retrieves an item object from the list that has a given text label.
Parameter Type Description

text String The text string to match.

void hide ()
Hides this element.

void notify ([eventName: String])
Sends a notification message, simulating the specified user interaction event.
Parameter Type Description

eventName String The name of the control event handler to call.
One of: onClick, onChange, onChanging. By default, simulates the onChange event for an edittext control, an onClick event for controls that support that event. (Optional)

void remove (what: Any)
Removes a child item from the list.
Parameter Type Description

what Any The item or child to remove, specified by 0-based index, text value, or as a ListItem object.

void removeAll ()
Removes all child items from the list.

Boolean removeEventListener (eventName: String, handler: Function[, capturePhase: Boolean=false])
Unregisters an event handler for a particular type of event occuring in this element.
All arguments must be identical to those that were used to register the event handler.
Parameter Type Description

eventName String The name of the event.

handler Function The function that handles the event.

capturePhase Boolean Whether to call the handler only in the capturing phase of the event propagation. (default: false)

void show ()
Shows this element.
When a window or container is hidden, its children are also hidden, but when it is shown again, the children retain their own visibility states.

Jongware, 25-Nov-2012 v3.0.3i

Contents :: Index